Getting Started with coLinux
coLinux is a wonderful tool for running Linux under Windows; it allows you to run a full-fledged Linux computer with no extra partitions, inside Windows. More information can be found at the home page. = Disclaimers = coLinux is still under heavy development, and will likely change in the future. This page represents the contributions of various coLinux users. The information may not be tailored to your environment. Like many open source projects, there's no warranty, blah blah blah. There is no guarantee that this program will operate correctly, or indeed, at all. = coLinux 0.6.1 and XP SP2 with PAE enabled = Version 0.6.1 has an issue with PAE, which is enabled by XP SP2 (it implements DEP/NX, which activates PAE as well). If you want to use 0.6.1 with XP SP2 disable DEP/NX and PAE, by adding the switches /noexecute=AlwaysOff /NOPAE to your boot.ini BEFORE you install coLinux 0.6.1 (you can do this with the msconfig tool which comes with Windows). The issue with PAE is fixed in coLinux 0.6.2 and later (release announcement). "AlwaysOff" needs for all current coLinux version with very new CPU and noexecute hardware support. =Terminology= ;Hosting OS: The system coLinux is installed on (usually Windows) ;coLinux OS: A coLinux instance running an operating system like Debian, Ubuntu, or Gentoo ;Adapter: Also called a "networking card". A piece of hardware which provides networking capabilites to a system = Overview = Generally, to use coLinux, one performs the following steps: *Download coLinux and run installation *Use the included terminal to log in *Use the most foolproof method to get network connectivity (usually slirp) *Update the system using apt-get or emerge *Install xterm or a complete desktop like GNOME or KDE *Install an X Server or VNC on the Host *use telnet, ssh, or a VNC client to connect to the Guest and start xterm, etc. *use scp, putty, cofs/smb, etc., to copy files between Host and Guest = Download and Installation = See Also README Go to the downloads section of the site, which is currently a link to the sourceforge downloads page. Download and run the most recent executable installer. # Although the installer doesn't default to it, "c:\coLinux" is a good install location. # During the install you are prompted to install WinPcap. This can be done with the coLinux installer open. # The TAP-Win32 Virtual Adapter device driver will be installed. # There is no harm in installing both WinPcap and TAP-Win32. For the latest development binaries and source (i.e. may crash your system), see snapshots * StepByStepInXP * TAP-Win32 driver * tapcontrol.exe can be used to test, install, upgrade and remove the tap driver from the command line. If you uninstall coLinux from one location and install it to another, the following procedure will update the Windows registry accordingly: colinux-daemon.exe --remove-driver colinux-daemon.exe --install-driver Filesystem Download From the main download site, also download a filesystem which includes an operating system. Debian-3.0r2.ext3-mit-backports.1gb.bz2 on SourceForge is a good choice. It expands to 1GB when decompressed. This has a basic Debian image on it with everything you need to get started. Save/extract this in the coLinux directory. Here is a partial list of programs which can extract the image, which is compressed using bzip2: *bunzip2 for windows on redhat *tar and bunzip2, included in unxutils *tar and bunzip2, included in cygwin *winrar *7Zip Run bunzip2 on Windows command line: bunzip2.exe Debian-3.0r2.ext3-mit-backports.1gb.bz2 = Configuration = coLinux can be configured using parameters on the command line, or with a configuration file like default.colinux.xml. For command-line options, see README. Configuring coLinux from the command line, or a windows .bat file looks something like this ("^" is the line continuation character in Windows).: Uses eth1 to talk to Hosting OS, eth0 for for Internet connectivity colinux-daemon.exe kernel=vmlinux initrd=initrd.gz ^ cobd0="Debian-20040605-mit.ext3.1610mb" ^ cobd1="fs_768Mb" ^ mem=512 ^ eth0=pcap-bridge,"Local Area Connection",00:ff:75:39:D3:C1 ^ eth1=tuntap ^ root=/dev/cobd0 Use ssh (port 22) or VNC (port 5901) to connect to coLinux guest system colinux-daemon kernel=vmlinux cobd0=Debian-20040605-mit.ext3.1610mb ^ cobd1="fs_768Mb" ^ mem=512 ^ eth0=slirp,"",tcp:22:22/tcp:5901:5901 ^ eth1=tuntap ^ root=/dev/cobd0 In the '''configuration file, options represent partitions. They are actually mounted under /dev/cobdn, where n is given by the index passed to it, and the path is fairly straightforward. Make sure that the first one (index="0") points to your root filesystem (e.g., the Debian image). You may want to disable the swap device for now; it's not strictly necessary and will be described later. The other options will work as-is. Memory You can take a quick look at the line and adjust it to fit your system. This is the physical amount of RAM you are going to allocate to coLinux, and you need to keep some to Windows. * if you have 128 Mb of RAM or less, don't bother with coLinux. ok, use 32 Mb... * 160 to 256 Mb of RAM : put the value 64 Mb * 256 to 512 Mb of RAM : you can increase to 96 Mb * 512 Mb and more : you can use 128 Mb or more if you want. those values are based on personnal experience, your mileage will vary. Oh, if you want, you can also tell coLinux your keyboard is not US with a command line like loadkeys fr-latin1. Then you have to configure the network. This is not strictly necessary to enjoy coLinux but you need it to : * download new software : the image you downloaded contains only a basic system, much like a bare Windows installation. * use ssh and PuTTY, a nice terminal since you will feel the console too unconfortable. * launch X applications and run VNC and see the results on your Windows screen. One note on the memory: this is non-swappable memory, so using too much can do bad things to your computer (as long as coLinux is running; as soon as you reboot, everything will be fine). It used to default to 29MB which was sufficient for most things, now it seems to default to 64MB. If you have less than 256MB of RAM you probably want to make it smaller. Realistically, unless you want to use X (described later) or use a very memory-intensive program, 32MB or even 16MB may be enough. = Running coLinux = c:\>cd coLinux c:\coLinux>colinux-daemon.exe -c default.colinux.xml or, to use a command shell as the terminal: c:\coLinux>colinux-daemon.exe -c default.colinux.xml -t nt *Some errors can be disregarded. Currently, errors that will appear when running a correctly-installed coLinux: Disabled Privacy Extensions on device c02bf040(lo) eth0: duplicate address detected! *To enable a double-click start, create a short-cut to the daemon (right-click and select Create Shortcut), and then right-click on that new shortcut and select Properties. In the Target box (under the Shortcut tab), add the following to the end of the existing text (after the double-quote, and don't forget the space before the -c!): -c default.colinux.xml and click OK. You can now double-click the shortcut (perhaps copy it to your desktop) to run CoLinux. If you would like to start the console minimised, select Minimized from the Run drop-down box. *Alternatively, you can put the following into a bat file such as coLinux.bat which you can double click: start "coLinux" /Dc:\colinux /min colinux-daemon.exe -c default.colinux.xml Remove /min if you want to see the boot messages. Change the /D to point to your coLinux dir. Added by PaulT) *The login for the debian image is root/root, you should change this. In another few seconds, a colinux-console should pop up. And after a few more seconds, it should stop and give you a login prompt. Since the Debian image by default has no other users, you must log in as root: * 2.4 distros - blank password * 2.6 distros - "root" as password Now you can use adduser to add another user for normal use, or passwd to set the root password. And you have Linux! Brushing the Dust off a Downloaded Root FS The Debian Root filesystems are a little long in the tooth. DebianRootFsImages is a procedure to bring the system up-to-date so that it is actually usable. Troubleshooting Blue screen of death (BSOD) * if you are getting a BSOD when starting coLinux, it is probably due to "AlwaysOff" not being set in boot.ini ** boot.ini is located in c:\ You need to enable viewing of system files before you can see this file in explorer. ** this file must be edited with a plain text editor, such as Notepad ** Be extremely careful editing this file! Incorrectly editing it could make your system unable to bootup ** when you edit the file you will see a line that looks like this: multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="WinXP Professional" /noexecute=optin /fastdetect ** copy that line, and paste it right below it. You will only be editing the second one. ** on that second line, change the text inbetween the double quotes to "WinXP for coLinux" ** also on that second line, change the / options at the end so that it only has "/noexecute=AlwaysOff /NOPAE" ** your new second line should look something like this: multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="WinXP for coLinux" /noexecute=AlwaysOff /NOPAE ** save boot.ini and reboot your computer ** when it reboots, there will be a text menu for you to choose. choose "WinXP for coLinux" ** when XP boots up, try starting coLinux again ** If something doesnt work right, you can reboot again and choose the first option on that text menu. That should start your system as it was before coLinux doesn't start * check the path to the uncompressed filesystem image * in the line with root=/dev/cobd0 add ro before root : ro root=/dev/cobd0 and be ready to remove it if it doesn't help. you can keep it, it is harmless in most cases (some distributions need it) * finally, take a close look at your text editor. there are some chances that it silently converted the text to UTF-8 and add a invisible marker at the beginning of your configuration file : switch to hexadecimal mode or to another editor and check the top of the file. if so, erase this marker. *in case of a error similar to daemon: exit code 84a08401 daemon: error - CO_RC_ERROR_ERROR, line 33, file colinux/os/current/user/file.o redo the following dance : colinux-daemon.exe --remove-driver colinux-daemon.exe --install-driver If that doesn't work you can check your parameters in config-file. Any filename for image, path to vmlinux or swapfile was wrong or don't exist. Comment out all not needed parameters to find the wrong entry in XML file. * If none of thse work, you can try Nitin Jain's install notes (listed in External references). Very good step-by-step directions = Using Other Linux Distributions in coLinux = The vanilla Debian may not be to your liking, or it may just seem a little hard to set up. You can find the instructions for configuring a specific distribution to use coLinux here: ConvertingDistributions. If you would like to use the Gentoo Deluxe 2 GB image look here: GentooDeluxHowto, or if you would like to use Topologi Linux look here: TopoHowTo. You can also download via BitTorrent a pre-configured coLinux setup based on coLinux-0.6.0 and the Debian filesystem - just download, extract, install, run. = Adding Swap Space = To add swap for use in your coLinux environment you need a filesystem file with the correct size of swap you want. Here is a location of a number of sizes of empty partitions. Name the file you downloaded per the line below in your default.colinux.xml file. Be sure to set the path too. # Boot into your coLinux system. # Login as root # Add the line below to /etc/fstab: /dev/cobd1 none swap sw 0 0 # Run "mkswap /dev/cobd1" # Run "swapon -a" Important Note for Gentoo Users Gentoo requires configuration of a swap file. Follow the instructions at AddSwapPartition = Network - Quick Start = The one-size-fits-all recipe for networking is to provision coLinux with two virtual adapters. One adapter connects to a LAN or the Internet, and the other adapter is a high-speed connection with the Hostinng OS First, create a TAP virtual adapter for private high-speed connection between the Hosting OS and the CoLinux OS. See Network#TAP_-_Private_Connection_with_Host_OS Second, Set up a [Slirp (easiest, slowest) or WinPcap (easy, faster) connection for getting on the Internet. = Network = See also Network Here are the most common configurations: WinPcap See also Network#The_WinPCAP_driver WinPcap is a good choice for use with a router. If you are behind any sort of router, and want the coLinux OS to be seen by the network just as any other normal computer attached to the network. Use this method. The coLinux OS will be able to use DHCP to request an IP address from the router, etc. In contrast to TAP, which provides another virtual network card on the Hosting OS, WinPcap lets the Hosting OS and the coLinux OS share the same network card. This is a good method to use together with a private TAP network Quickstart: *Install WinPcap when prompted during coLinux installation. *Modify the "network" line in the coLinux configuration file: In the above line, change "Local Area Connection" to the name of your connection as reported by "ipconfig" TAP See Also Network#TAP After you create a virtual adapter, on the Hosting OS with TAP, all the options of configuring a real ethernet adapter are available. A common method is to use Windows Internet Connection Sharing to share a network connection to a coLinux OS connected to a TAP virtual adapter. For example, Microsoft Software Bridge could be used to bridge the TAP adapter to another adapter. This would result in a setup which functions much like WinPcap. Slirp See also Network#Slirp Scenario The coLinux monitor itself acts as a DHCP server, granting the coLinux instance a private ip address and mediating all network communications. "Outgoing calls" from the coLinux box work as expected. Slirp can be configured forward a ports from the Host operating system to the Guest operating system. Other than this port forwarding capability, the coLinux Guest is invisible to the network. Using Slirp port forwarding, it is possible to ssh to the Guest, connect using vnc, etc. Port forwarding is not required to run xclients like xterm. = Graphical Interface (Xserver) = The article XCoLinux explains how to run an X server on the Host and xclient applications in coLinux External Resources : Nitin Jain's install notes 2006-07. : Evan Danaher's notes 2005 or earlier.